SGI Freeware 1999 August/SGI Freeware 1999 August.iso/dist/fw_gnats.idb/usr/freeware/info/gnats.info-1.z/gnats.info-1

GNU Info File | 1999-04-16 | 45.8 KB | 1,202 lines

This is Info file gnats.info, produced by Makeinfo-1.55 from the input
file ./gnats.texi.

START-INFO-DIR-ENTRY
* Keeping Track: (gnats).        GNU Problem Report Management System
END-INFO-DIR-ENTRY

   Copyright (C) 1993 Free Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the entire resulting derived work is distributed under the terms
of a permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions.


File: gnats.info,  Node: Top,  Next: Introduction,  Prev: (DIR),  Up: (DIR)

Overview
********

   This manual documents GNATS, the GNU Problem Report Management
System, version 3.2.  GNATS is a bug-tracking tool designed for use at
a central "Support Site".  Users who experience problems use electronic
mail to communicate these problems to "maintainers" at that Support
Site.  GNATS partially automates the tracking of these "Problem
Reports" ("PR"s) by:

   * organizing problem reports into a database and notifying
     responsible parties of suspected bugs;

   * allowing support personnel and their managers to edit and query
     accumulated bugs; and

   * providing a reliable archive of problems (and their subsequent
     solutions) with a given program.

   GNATS offers many of the same features offered by more generalized
databases, including editing, querying, and basic reporting.  The GNATS
database itself is an ordered repository for problem reports; each PR
receives a unique, incremental "PR number" which identifies it
throughout its lifetime.  For a discussion on the working system
adopted by GNATS, see *Note The database paradigm: Paradigm.

   You can access the submitting, editing, and querying functions of
GNATS from within GNU Emacs.  *Note Invoking the GNATS tools: Invoking
the tools.

* Menu:

* Introduction::          Introducing GNATS
* Invoking the tools::    Invoking the GNATS tools
* Management::            GNATS Administration
* Installation::          Installing GNATS
* Locations::             Where GNATS lives
* Regexps::               Querying using regular expressions
* Index::


File: gnats.info,  Node: Introduction,  Next: Invoking the tools,  Prev: Top,  Up: Top

Introducing GNATS
*****************

   Any support organization realizes that a large amount of data flows
back and forth between the maintainers and the users of their products.
This data often takes the form of problem reports and communication via
electronic mail.  GNATS addresses the problem of organizing this
communication by defining a database made up of archived and indexed
electronic mail messages.

   GNATS was designed as a tool for software maintainers.  It consists
of several utilities which, when used in concert, formulate and
administer a database of Problem Reports grouped by site-defined
"problem categories".  It allows a support organization to keep track
of problems (hence the term "Problem Report") in an organized fashion.
Essentially, GNATS acts as an active archive for field-separated
textual data submitted through electronic mail.

* Menu:

* Paradigm::       The database paradigm
* Flowchart::      Flowchart of GNATS activities
* States::         States of Problem Reports
* Fields::         Problem Report format


File: gnats.info,  Node: Paradigm,  Next: Flowchart,  Up: Introduction

The database paradigm
=====================

   It is in your best interest as the maintainer of a body of work to
organize the feedback you receive on that work, and to make it easy for
users of your work to report problems and suggestions.

   GNATS makes this easy by automatically filing incoming problem
reports into appropriate places, by notifying responsible parties of the
existence of the problem and (optionally) sending an acknowledgement to
the submitter that the report was received, and by making these Problem
Reports accessible to queries and easily editable.  GNATS is a database
specialized for a specific task.

   GNATS was designed for use at a Support Site that handles a high
level of problem-related traffic though electronic mail.  It maintains
Problem Reports in the form of text files with defined "fields" (*note
GNATS data fields: Fields.).  The location of the database, as well as
the categories it accepts as valid, the maintainers for whom it
provides service, and the submitters from whom it accepts Problem
Reports, are all definable by the "Support Site".  *Note GNATS
administration: Management.

   Each PR is a separate file within a main repository (*note Where
GNATS lives: Locations.).  Editing access to the database is regulated
to maintain consistency, but anyone with electronic mail access may
submit Problem Reports.  To make queries on the database faster, an
index is kept automatically (*note The `index' file: index file.).

   We provide several software tools so that users may submit new
Problem Reports, edit existing Problem Reports, and query the database.

   * `send-pr' is used by both product maintainers and the end users of
     the products they support to submit PRs to the database.

   * `edit-pr' is used by maintainers to use when editing problem
     reports in the database.

   * Maintainers, managers and administrators can use `query-pr' to
     make inquiries about indidvidual PRs or groups of PRs.

   `send-pr' can also be packaged by itself  and distributed to anyone
you wish to receive Problem  Reports  from; see *Note Configuring
`send-pr' for the outside world: mkdist.

   At the Support Site, a GNATS "administrator" is charged with the
duty of maintaining GNATS.  These duties are discussed in detail in
*Note GNATS Administration: Management, and generally include
configuring GNATS for the Support Site, editing PRs that GNATS cannot
process, pruning log files, setting up new problem categories, backing
up the database, and distributing `send-pr' so that others may submit
Problem Reports.

   Responsibility for a given Problem Report depends on the category of
the problem.  Optionally, an automated reminder can be sent to the
responsible person if a problem report is neglected for a requisite time
period.  *Note Changing your local configuration: Local configuration.

   GNATS does not have the ability to decipher random text, so any
problem reports which arrive in a format GNATS does not recognize are
placed in a separate directory pending investigation by the GNATS
administrator (*note GNATS Administration: Management.).

   Once a problem is recorded in the database, work can begin toward a
solution.  A problem's initial "state" is `open' (*note States of
Problem Reports: States.).  An acknowledgement is sent to the
originator of the bug report (if that feature of GNATS is activated).
gNATS forwards copies of the report to the party responsible for that
problem category and to the person responsible for problems arriving
from that "Submitter Site".

   When a problem has been identified, the maintainer can change its
state to `analyzed', and then to `feedback' when a solution is found.
Each time the state of a PR changes, the submitter of the problem
report is notified of the reason for the change.  If the party
responsible for the PR changes, the previous responsible party and the
new responsible party receive notice of the change.  The change and
reason are also recorded in the `>Audit-Trail:' field of the Problem
Report.  (*Note Editing existing Problem Reports: edit-pr.  For
information on the `>Audit-Trail:' field, see *Note Problem Report
format: Fields.)

   When the originator of the Problem Report confirms that the solution
works, the maintainer can change the state to "closed".  If the PR
cannot be closed, the maintainer can change its state to "suspended" as
a last resort.  (For a more detailed description of these states, see
*Note States of Problem Reports: States.)


File: gnats.info,  Node: Flowchart,  Next: States,  Prev: Paradigm,  Up: Introduction

Flowchart of GNATS activities
=============================

   This informal flowchart shows the relationships of the GNATS tools
to each other and to the files with which they interoperate.

     +===========+    +===========+    +===========+
     # USER SITE #    # USER SITE #    # USER SITE #
     #           #    #           #    #           #
     # *send-pr* #    # *send-pr* #    # *send-pr* #
     +=====|=====+    +=====|=====+    +=====|=====+
           |                V                |
           `--------->    Email....  <-------'
                     ,--->     |
     +===============|=========|===================+
     # SUPPORT SITE  |         `---> /etc/aliases  #
     #          *send-pr*                |         #
     #     +-----------------------------V--------+#
     #     | GNATS         GNATS_ROOT/gnats-queue/|#
     #     |                             |        |#
     #     |        _________            V        |#
     #     |       |*file-pr*|<--- *queue-pr -r*  |#
     #     |       |         |                    |#
     #  _  |       |  valid  |                    |#
     # |M| |       |Category?|N--.                |#
     # |A| |       |_________|   |      GNATS     |#
     # |I| |              Y|     |  ADMINISTRATOR |#
     # |N| |               |     |                |#
     # |T|<----------------|     |                |#
     # |A| |               |     |  .-> *edit-pr* |#
     # |I|--->*edit-pr*-.  |     V  |           | |#
     # |N| |            |  |GNATS_ROOT/pending  | |#
     # |E|<--*query-pr* |  |                    | |#
     # |R| |       |    |  |                    | |#
     # |S| |       |    V  V                    V |#
     # |_| |+------------------------------------+|#
     #     ||         GNATS Database             ||#
     #     ||   GNATS_ROOT/CATEGORY/GNATS-ID     ||#
     #     |+------------------------------------+|#
     #     +--------------------------------------+#
     +=============================================+


File: gnats.info,  Node: States,  Next: Fields,  Prev: Flowchart,  Up: Introduction

States of Problem Reports
=========================

   Each PR goes through a defined series of states between origination
and closure.  The originator of a PR receives notification
automatically of any state changes.

"open"
     The initial state of a Problem Report.  This means the PR has been
     filed and the responsible person(s) notified.

"analyzed"
     The responsible person has analyzed the problem.  The analysis
     should contain a preliminary evaluation of the problem and an
     estimate of the amount of time and resources necessary to solve
     the problem.  It should also suggest possible workarounds.

"feedback"
     The problem has been solved, and the originator has been given a
     patch or other fix.  The PR remains in this state until the
     originator acknowledges that the solution works.

"closed"
     A Problem Report is closed ("the bug stops here") only when any
     changes have been integrated, documented, and tested, and the
     submitter has confirmed the solution.

"suspended"
     Work on the problem has been postponed.  This happens if a timely
     solution is not possible or is not cost-effective at the present
     time.  The PR continues to exist, though a solution is not being
     actively sought.  If the problem cannot be solved at all, it
     should be closed rather than suspended.


File: gnats.info,  Node: Fields,  Prev: States,  Up: Introduction

Problem Report format
=====================

   The format of a PR is designed to reflect the nature of GNATS as a
database.  Information is arranged into "fields", and kept in
individual records (Problem Reports).

   Problem Report fields are denoted by a keyword which begins with `>'
and ends with `:', as in `>Confidential:'.  Fields belong to one of
three data types:

ENUMERATED
     One of a specific set of values, which vary according to the
     field.  The value for each keyword must be on the same line as the
     keyword.  These values are not configurable (yet).

     The following fields are ENUMERATED format; see the descriptions of
     fields below for explanations of each field in detail:

          >Confidential:   >Severity:       >Priority:
          >Class:          >State:          >Number:

TEXT
     One single line of text which must begin and end on the same line
     (i.e., before a newline) as the keyword.  See the descriptions of
     fields below for explanations of each field in detail.  The
     following fields are TEXT format:

          >Submitter-Id:   >Originator:     >Synopsis:
          >Category:       >Release:        >Responsible:
          >Arrival-Date:

MULTITEXT
     Text of any length may occur in this field.  MULTITEXT may span
     multiple lines and may also include blank lines.  A MULTITEXT field
     ends only when another keyword appears.  See the descriptions of
     fields below for explanations of each field in detail.

     The following fields are MULTITEXT format:

          >Organization:   >Environment:    >Description:
          >How-To-Repeat:  >Fix:            >Audit-Trail:
          >Unformatted:

   A Problem Report contains two different types of fields: "Mail
Header" fields, which are used by the mail handler for delivery, and
"Problem Report" fields, which contain information relevant to the
Problem Report and its submitter.  A Problem Report is essentially a
specially formatted electronic mail message.

Example Problem Report
----------------------

   The following is an example Problem Report.  Mail headers are at the
top, followed by GNATS fields, which begin with `>' and end with `:'.
The `Subject:' line in the mail header and the `>Synopsis:' field are
usually duplicates of each other.

     Message-Id:  MESSAGE-ID
     Date:        DATE
     From:        ADDRESS
     Reply-To:    ADDRESS
     To:          BUG-ADDRESS
     Subject:     SUBJECT

     >Number:       GNATS-ID
     >Category:     CATEGORY
     >Synopsis:     SYNOPSIS
     >Confidential: yes *or* no
     >Severity:     critical, serious, *or* non-critical
     >Priority:     high, medium *or* low
     >Responsible:  RESPONSIBLE
     >State:        open, analyzed, suspended, feedback, *or* closed
     >Class:        sw-bug, doc-bug, change-request, support,
     duplicate, *or* mistaken
     >Submitter-Id: SUBMITTER-ID
     >Arrival-Date: DATE
     >Originator:   NAME
     >Organization: ORGANIZATION
     >Release:      RELEASE
     >Environment:
        ENVIRONMENT
     >Description:
        DESCRIPTION
     >How-To-Repeat:
        HOW-TO-REPEAT
     >Fix:
        FIX
     >Audit-Trail:
     APPENDED-MESSAGES...
     State-Changed-From-To: FROM-TO
     State-Changed-When: DATE
     State-Changed-Why:
        REASON
     Responsible-Changed-From-To: FROM-TO
     Responsible-Changed-When: DATE
     Responsible-Changed-Why:
        REASON
     >Unformatted:
        MISCELLANEOUS

* Menu:

* Mail header fields::
* Problem Report fields::


File: gnats.info,  Node: Mail header fields,  Next: Problem Report fields,  Up: Fields

Mail header fields
------------------

   A Problem Report may contain any mail header field described in the
Internet standard RFC-822.  However, only the fields which identify the
sender and the subject are required by `send-pr':

`To:'
     The preconfigured mail address for the Support Site where the PR
     is to be sent, automatically supplied by `send-pr'.

`Subject:'
     A terse description of the problem.  This field normally contains
     the same information as the `>Synopsis:' field.

`From:'
     Usually supplied automatically by the originator's mailer; should
     contain the originator's electronic mail address.

`Reply-To:'
     A return address to which electronic replies can be sent; in most
     cases, the same address as the `From:' field.

   One of the configurable options for GNATS is whether or not to
retain `Received-By:' headers, which often consume a lot of space and
are not often used.  *Note Changing your local configuration: Local
configuration.


File: gnats.info,  Node: Problem Report fields,  Prev: Mail header fields,  Up: Fields

Problem Report fields
---------------------

Field descriptions
------------------

   The following fields are present whenever a PR is submitted via the
program `send-pr'.  GNATS adds additional fields when the PR arrives at
the Support Site; explanations of these follow this list.

`>Submitter-Id:'
     (TEXT) A unique identification code assigned by the Support Site.
     It is used to identify all Problem Reports coming from a particular
     site.  (Submitters without a value for this field can invoke
     `send-pr' with the `--request-id' option to apply for one from the
     support organization.  Problem Reports from those not affiliated
     with the support organization should use the default value of `net'
     for this field.)

`>Originator:'
     (TEXT) Originator's real name.  The default is the value of the
     originator's environment variable `NAME'.

`>Organization:'
     (MULTITEXT) The originator's organization.  The default value is
     set with the variable `DEFAULT_ORGANIZATION' in the `config' file
     (*note The `config' file: config.).

`>Confidential:'
     (ENUMERATED) Use of this field depends on the originator's
     relationship with the support organization; contractual agreements
     often have provisions for preserving confidentiality.  Conversely,
     a lack of a contract often means that any data provided will not
     be considered confidential.  Submitters should be advised to
     contact the support organization directly if this is an issue.

     If the originator's relationship to the support organization
     provides for confidentiality, then if the value of this field is
     `yes' the support organization treats the PR as confidential; any
     code samples provided are not made publicly available (e.g., in
     regression test suites).  The default value is `yes'.

`>Synopsis:'
     (TEXT) One-line summary of the problem.  `send-pr' copies this
     information to the `Subject:' line when you submit a Problem
     Report.

`>Severity:'
     (ENUMERATED) The severity of the problem.  Accepted values include:

    `critical'
          The product, component or concept is completely
          non-operational or some essential functionality is missing.
          No workaround is known.

    `serious'
          The product, component or concept is not working properly or
          significant functionality is missing.  Problems that would
          otherwise be considered `critical' are rated `serious' when a
          workaround is known.

    `non-critical'
          The product, component or concept is working in general, but
          lacks features, has irritating behavior, does something
          wrong, or doesn't match its documentation.  The default value
     is `serious'.

`>Priority:'
     (ENUMERATED) How soon the originator requires a solution.  Accepted
     values include:

    `high'
          A solution is needed as soon as possible.

    `medium'
          The problem should be solved in the next release.

    `low'
          The problem should be solved in a future release.

     The default value is `medium'.

`>Category:'
     (TEXT) The name of the product, component or concept where the
     problem lies.  The values for this field are defined by the Support
     Site.  *Note The `categories' file: categories, for details.

`>Class:'
     (ENUMERATED) The class of a problem can be one of the following:

    `sw-bug'
          A general product problem.  (`sw' stands for "software".)

    `doc-bug'
          A problem with the documentation.

    `change-request'
          A request for a change in behavior, etc.

    `support'
          A support problem or question.

    `duplicate (PR-NUMBER)'
          Duplicate PR.  PR-NUMBER should be the number of the original
          PR.

    `mistaken'
          No problem, user error or misunderstanding.  This value is
          valid only at the Support Site.

     The default is `sw-bug'.

`>Release:'
     (TEXT) Release or version number of the product, component or
     concept.

`>Environment:'
     (MULTITEXT) Description of the environment where the problem
     occured: machine architecture, operating system, host and target
     types, libraries, pathnames, etc.

`>Description:'
     (MULTITEXT) Precise description of the problem.

`>How-To-Repeat:'
     (MULTITEXT) Example code, input, or activities to reproduce the
     problem.  The support organization uses example code both to
     reproduce the problem and to test whether the problem is fixed.
     Include all preconditions, inputs, outputs, conditions after the
     problem, and symptoms.  Any additional important information
     should be included.  Include all the details that would be
     necessary for someone else to recreate the problem reported,
     however obvious.  Sometimes seemingly arbitrary or obvious
     information can point the way toward a solution.  See also *Note
     Helpful hints: Helpful hints.

`>Fix:'
     (MULTITEXT) A description of a solution to the problem, or a patch
     which solves the problem.  (This field is most often filled in at
     the Support Site; we provide it to the submitter in case she has
     solved the problem.)

GNATS adds the following fields when the PR arrives at the Support Site:

`>Number:'
     (ENUMERATED) The incremental identification number for this PR.
     This is included in the automated reply to the submitter (if that
     feature of GNATS is activated; *note Changing your local
     configuration: Local configuration.).  It is also included in the
     copy of the PR that is sent to the maintainer.

     The `>Number:' field is often paired with the `>Category:' field as

          CATEGORY/NUMBER

     in subsequent email messages.  This is for historical reasons, as
     well as because Problem Reports are stored in subdirectories which
     are named by category.

`>State:'
     (ENUMERATED) The current state of the PR.  Accepted values are:

    `open'
          The PR has been filed and the responsible person notified.

    `analyzed'
          The responsible person has analyzed the problem.

    `feedback'
          The problem has been solved, and the originator has been
          given a patch or other fix.

    `closed'
          The changes have been integrated, documented, and tested, and
          the originator has confirmed that the solution works.

    `suspended'
          Work on the problem has been postponed.

     The initial state of a PR is `open'.  *Note States of Problem
     Reports: States.

`>Responsible:'
     (TEXT) The person responsible for this category.  GNATS retrieves
     this information from the `categories' file (*note The
     `categories' file: categories.).

`>Arrival-Date:'
     (TEXT) The time that this PR was received by GNATS.  The date is
     provided automatically by GNATS.

`>Audit-Trail:'
     (MULTITEXT) Tracks related electronic mail as well as changes in
     the `>State:' and `>Responsible:' fields with the sub-fields:

    `State-Changed-<From>-<To>: OLDSTATE>-<NEWSTATE'
          The old and new `>State:' field values.

    `Responsible-Changed-<From>-<To>: OLDRESP>-<NEWRESP'
          The old and new `>Responsible:' field values.

    `State-Changed-By: NAME'
    `Responsible-Changed-By: NAME'
          The name of the maintainer who effected the change.

    `State-Changed-When: TIMESTAMP'
    `Responsible-Changed-When: TIMESTAMP'
          The time the change was made.

    `State-Changed-Why: REASON...'
    `Responsible-Changed-Why: REASON...'
          The reason for the change.

     The `>Audit-Trail:' field also contains any mail messages received
     by GNATS related to this PR, in the order received.

`>Unformatted:'
     (MULTITEXT) Any random text found outside the fields in the
     original Problem Report.


File: gnats.info,  Node: Invoking the tools,  Next: Management,  Prev: Introduction,  Up: Top

Invoking the GNATS tools
************************

   The following programs comprise GNATS:

User Utilities
--------------

   These tools are used by the maintainers of a body of work (`send-pr'
is also used by the end users of the product).

`send-pr'
     Used by anyone who has a problem with a body of work to submit a
     report of the problem to the maintainers of that work (*note
     Submitting Problem Reports: send-pr.).

`query-pr'
     Used by software maintainers to query the GNATS database (*note
     Querying the database: query-pr.).

`edit-pr'
     Used by software maintainers to edit Problem Reports (to record new
     data, to change the responsible party, etc.) (*note Editing
     existing Problem Reports: edit-pr.).

`view-pr'
     Used by software maintainers to view individual Problem Reports
     using Emacs (*note Viewing individual Problem Reports: view-pr.).

Administrative Utilities
------------------------

   These tools are used by the GNATS administrator; see also *Note
GNATS Administration: Management.  For complete explanations of these
utilities, see *Note Administrative utilities: Admin utils.

`mkcat'
     Creates new categories (*note Adding a problem category: mkcat.).

`rmcat'
     Removes existing categories (*note Removing a problem category:
     rmcat.).

`gen-index'
     Generates an up-to-date copy of the index used by `query-pr' and
     `edit-pr' (*note The `index' file: index file.).  Use `gen-index'
     to rebuild the index if it becomes corrupted, or if you need a
     copy of the current index for some reason (*note Regenerating the
     index: gen-index.).

`mkdist'
     Creates a distribution of the program `send-pr' for offsite
     submitters of PRs (*note Configuring `send-pr' for the outside
     world: mkdist.).

Internal Utilities
------------------

   These tools are used internally by GNATS.  You should not need to
run these by hand.  For complete explanations of these utilities, see
*Note Internal utilities: Internal utils.

`queue-pr'
     Handles incoming bugs, first through a mail alias by queueing
     incoming PRs as they arrive, and second as a periodic transfer
     agent between the queue and the database.

`file-pr'
     Files Problem Reports as they come in.

`at-pr'
     Sends reminders to maintainers based on quoted response times.

`pr-edit'
     Used by `edit-pr' to error-check and submit edited Problem Reports
     (also *note Editing existing Problem Reports: edit-pr.).

`pr-addr'
     Used by the `edit-pr' script to retrieve correct addresses from the
     `responsible' file.

   *Note Where GNATS lives: Locations.

* Menu:

* send-pr::           Submitting Problem Reports
* edit-pr::           Editing existing Problem Reports
* query-pr::          Querying the database
* view-pr::           Viewing individual Problem Reports


File: gnats.info,  Node: send-pr,  Next: edit-pr,  Up: Invoking the tools

Submitting Problem Reports
==========================

   Use `send-pr' to submit Problem Reports to the database.  `send-pr'
is both a shell script and a Lisp program for GNU Emacs; both
implementations provide a template for submitters to complete.  In most
cases, `send-pr' can determine intelligent default values for several
fields, partially automating the bug-reporting process.

   *Note Configuring `send-pr' for the outside world: mkdist, for
information on distributing a version of `send-pr' customized with your
site's configuration.

   You can invoke `send-pr' from a shell prompt or from within GNU
Emacs using `M-x send-pr'.

* Menu:

* using send-pr::             Creating new Problem Reports
* send-pr in Emacs::          Using send-pr from within Emacs
* send-pr from the shell::    Invoking send-pr from the shell
* Helpful hints::


File: gnats.info,  Node: using send-pr,  Next: send-pr in Emacs,  Up: send-pr

Creating new Problem Reports
----------------------------

   Invoking `send-pr' presents a PR "template" with a number of fields
already filled in.  Complete the template as thoroughly as possible to
make a useful bug report.  Submit only one bug with each PR.

   A template consists of three sections:

"Comments"
     The top several lines of a blank template consist of a series of
     comments that provide some basic instructions for completing the
     Problem Report, as well as a list of valid entries for the
     `>Category:' field.  These comments are all preceded by the string
     `SEND-PR:' and are erased automatically when the PR is submitted.
     The instructional comments within `<' and `>' are also removed.
     (Only these comments are removed; lines you provide that happen to
     have those characters in them, such as examples of shell-level
     redirection, are not affected.)

"Mail Header"
     `send-pr' creates a standard mail header.  `send-pr' completes all
     fields except the `Subject:' line with default values.  (*Note
     Problem Report format: Fields.)

"GNATS fields"
     These are the informational fields that GNATS uses to route your
     Problem Report to the responsible party for further action.  They
     should be filled out as completely as possible.  (*Note Problem
     Report format: Fields.  Also see *Note Helpful hints: Helpful
     hints.)

   The default template contains your preconfigured `>Submitter-Id:'.
`send-pr' attempts to determine values for the `>Originator:' and
`>Organization:' fields (*note Problem Report format: Fields.).
`send-pr' also attempts to find out some information about your system
and architecture, and places this information in the `>Environment:'
field if it finds any.

   You may submit problem reports to different Support Sites from the
default site by specifying the alternate site when you invoke
`send-pr'.  Each `site' has its own list of categories for which it
accepts Problem Reports.

   `send-pr' also provides the mail header section of the template with
default values in the `To:', `From:', and `Reply-To:' fields.  The
`Subject:' field is empty.

   The template begins with a comment section:

     SEND-PR: -*- send-pr  -*-
     SEND-PR: Lines starting with `SEND-PR' will be removed
     SEND-PR: automatically as well as all comments (the text
     SEND-PR: below enclosed in `<' and `>').
     SEND-PR:
     SEND-PR: Please consult the document `Reporting Problems
     SEND-PR: Using send-pr' if you are not sure how to fill out
     SEND-PR: a problem report.
     SEND-PR:
     SEND-PR: Choose from the following categories:

and also contains a list of valid `>Category:' values for the Support
Site to whom you are submitting this Problem Report.  One (and only
one) of these values should be placed in the `>Category:' field.

   The mail header is just below the comment section.  Fill out the
`Subject:' field, if it is not already completed using the value of
`>Synopsis:'.  The other mail header fields contain default values.

     To: SUPPORT-SITE
     Subject: *complete this field*
     From: YOUR-LOGIN@YOUR-SITE
     Reply-To: YOUR-LOGIN@YOUR-SITE
     X-send-pr-version: send-pr 3.2

where SUPPORT-SITE is an alias for the Support Site you wish to submit
this PR to.

   The rest of the template contains GNATS fields.  Each field is
either automatically completed with valid information (such as your
`>Submitter-Id:') or contains a one-line instruction specifying the
information that field requires in order to be correct.  For example,
the `>Confidential:' field expects a value of `yes' or `no', and the
answer must fit on one line; similarly, the `>Synopsis:' field expects
a short synopsis of the problem, which must also fit on one line.  Fill
out the fields as completely as possible.  *Note Helpful hints: Helpful
hints, for suggestions as to what kinds of information to include.

   In this example, words in *italics* are filled in with
pre-configured information:

     >Submitter-Id: *your submitter-id*
     >Originator:   *your name here*
     >Organization:
         *your organization*
     >Confidential:<[ yes | no ] (one line)>
     >Synopsis:    <synopsis of the problem (one line)>
     >Severity:    <[non-critical | serious | critical](one line)>
     >Priority:    <[ low | medium | high ] (one line)>
     >Category:    <name of the product (one line)>
     >Class:       <[sw-bug | doc-bug | change-request | support]>
     >Release:     <release number or tag (one line)>
     >Environment:
              <machine, os, target, libraries (multiple lines)>

     >Description:
            <precise description of the problem (multiple lines)>
     >How-To-Repeat:
            <code/input/activities to reproduce (multiple lines)>
     >Fix:
            <how to correct or work around the problem, if known
             (multiple lines)>

   When you finish editing the Problem Report, `send-pr' mails it to
the address named in the `To:' field in the mail header.  `send-pr'
checks that the complete form contains a valid `>Category:'.

   If your PR has an invalid value in one of the ENUMERATED fields
(*note Problem Report format: Fields.), `send-pr' places the PR in a
temporary file named `/tmp/pbadNNNN' on your machine.  NNNN is the
process identification number given to your current `send-pr' session.
If you are running `send-pr' from the shell, you are prompted as to
whether or not you wish to try editing the same Problem Report again.
If you are running `send-pr' from Emacs, the Problem Report is placed
in the buffer `*send-pr-error*'; you can edit this file and then submit
it with

     M-x gnats-submit-pr

   Any further mail concerning this Problem Report should be
carbon-copied to the GNATS mailing address as well, with the category
and identification number in the `Subject:' line of the message.

     Subject: Re: PR CATEGORY/GNATS-ID: ORIGINAL MESSAGE SUBJECT

Messages which arrive with `Subject:' lines of this form are
automatically appended to the Problem Report in the `>Audit-Trail:'
field in the order received.


File: gnats.info,  Node: send-pr in Emacs,  Next: send-pr from the shell,  Prev: using send-pr,  Up: send-pr

Using `send-pr' from within Emacs
---------------------------------

   You can use an interactive `send-pr' interface from within GNU Emacs
to fill out your Problem Report.  We recommend that you familiarize
yourself with Emacs before using this feature (*note Introduction:
(emacs)Introduction.).

   Call `send-pr' with `M-x send-pr'.(1)  `send-pr' responds with a
Problem Report template preconfigured for the Support Site from which
you received `send-pr'.  (If you use `send-pr' locally, the default
Support Site is probably your local site.)

   You may also submit problem reports to different Support Sites from
the default site.  To use this feature, invoke `send-pr' with

     C-u M-x send-pr

   `send-pr' prompts you for the name of a SITE.  SITE is an alias on
your local machine which points to an alternate Support Site.

   `send-pr' displays the template and prompts you in the minibuffer
with the line:
     >Category: other

Delete the default value `other' *in the minibuffer* and replace it
with the keyword corresponding to your problem (the list of valid
categories is in the topmost section of the PR template).  For example,
if the problem you wish to report has to do with the GNU C compiler,
and your support organization accepts bugs submitted for this program
under the category `gcc', delete `other' and then type `gcc[RET]'.
`send-pr' replaces the line

     >Category:       <name of the product (one line)>

in the template with

     >Category:       gcc

and moves on to another field.

   `send-pr' provides name completion in the minibuffer.  For instance,
you can also type `gc[TAB]', and `send-pr' attempts to complete the
entry for you.  Typing `g[TAB]' may not have the same effect if several
possible entries begin with `g'.  In that case `send-pr' cannot
complete the entry because it cannot determine whether you mean `gcc'
or, for example, `gdb', if both of those are possible categories.
`send-pr' continues to prompt you for a valid entry until you enter one.

   `send-pr' prompts you interactively to enter each field for which
there is a range of specific choices.  If you attempt to enter a value
which is not in the range of acceptable entries, `send-pr' responds
with `[No match]' and allows you to change the entry until it contains
an acceptable value.  This avoids unusable information (at least in
these fields) and also avoids typographical errors which could cause
problems later.

   `send-pr' prompts you for the following fields:

     >Category:
     >Confidential: (*default*:  no)
     >Severity:     (*default*:  serious)
     >Priority:     (*default*:  medium)
     >Class:        (*default*:  sw-bug)
     >Release:
     >Synopsis:     (*this value is copied to `Subject:'*)

After you complete these fields, `send-pr' places the cursor in the
`>Description:' field and displays the message

     To send the problem report use: C-c C-c

in the minibuffer.  At this point, edit the file in the main buffer to
reflect your specific problem, putting relevant information in the
proper fields.

   `send-pr' provides a few key bindings to make moving around in a
template buffer more simple:

`C-c C-f'
`M-x change-field'
     Changes the field under the cursor.  `edit-pr' prompts you for a
     new value.

`M-C-b'
`M-x gnats-backward-field'
     Moves the cursor to the beginning of the value of the current
     field.

`M-C-f'
`M-x gnats-forward-field'
     Moves the cursor to the end of the value of the current field.

`M-p'
`M-x gnats-previous-field'
     Moves the cursor back one field to the beginning of the value of
     the previous field.

`M-n'
`M-x gnats-next-field'
     Moves the cursor forward one field to the beginning of the value
     of the next field.

   `send-pr' takes over again when you type `C-c C-c' to send the
message.  `send-pr' reports any errors in a separate buffer, which
remains in existence until you send the PR properly (or, of course,
until you explicitly kill the buffer).

   For detailed instructions on using Emacs, see *Note Introduction:
(emacs)Introduction.

   ---------- Footnotes ----------

   (1)  If typing `M-x send-pr' doesn't work, see your system
administrator for help loading `send-pr' into Emacs.


File: gnats.info,  Node: send-pr from the shell,  Next: Helpful hints,  Prev: send-pr in Emacs,  Up: send-pr

Invoking `send-pr' from the shell
---------------------------------

     send-pr [ SITE ]
             [ -f PROBLEM-REPORT | --file PROBLEM-REPORT ]
             [ -t MAIL-ADDRESS | --to MAIL-ADDRESS ]
             [ --request-id ]
             [ -L | --list ] [ -P | --print ]
             [ -V | --version] [ -h | --help ]

   SITE is an alias on your local machine which points to an address
used by a Support Site.  If this argument is not present, the default
SITE is usually the site which you received `send-pr' from, or your
local site if you use GNATS locally.

   Invoking `send-pr' with no options calls the editor named in your
environment variable `EDITOR' on a default PR template.  If the
environment variable `PR_FORM' is set, its value is used as a file name
which contains a valid template.  If `PR_FORM' points to a missing or
unreadable file, or if the file is empty, `send-pr' generates an error
message and opens the editor on a default template.

`-f PROBLEM-REPORT'
`--file PROBLEM-REPORT'
     Specifies a file, PROBLEM-REPORT, where a completed Problem Report
     already exists.  `send-pr' sends the contents of the file without
     invoking an editor.  If PROBLEM-REPORT is `-', `send-pr' reads
     from standard input.

`-t MAIL-ADDRESS'
`--to MAIL-ADDRESS'
     Sends the PR to MAIL-ADDRESS. The default is preset when `send-pr'
     is configured.  *This option is not recommended*; instead, use the
     argument SITE on the command line.

`--request-id'
     Sends a request for a `>Submitter-Id:' to the Support Site.

`-L'
`--list'
     Prints the list of valid `>Category:' values on standard output.
     No mail is sent.

`-P'
`--print'
     Displays the PR template.  If the variable `PR_FORM' is set in your
     environment, the file it specifies is printed.  If `PR_FORM' is not
     set, `send-pr' prints the standard blank form.  If the file
     specified by `PR_FORM' doesn't exist, `send-pr' displays an error
     message.  No mail is sent.

`-V'
`--version'
     Displays the `send-pr' version number and a usage summary.  No mail
     is sent.

`-h'
`--help'
     Displays a usage summary for `send-pr'.  No mail is sent.


File: gnats.info,  Node: Helpful hints,  Prev: send-pr from the shell,  Up: send-pr

Helpful hints
-------------

   There is no orthodox standard for submitting effective bug reports,
though you might do well to consult the section on submitting bugs for
GNU `gcc' in *Note Reporting Bugs: (gcc)Bugs, by Richard Stallman.
This section contains instructions on what kinds of information to
include and what kinds of mistakes to avoid.

   In general, common sense (assuming such an animal exists) dictates
the kind of information that would be most helpful in tracking down and
resolving problems in software.
   * Include anything *you* would want to know if you were looking at
     the report from the other end.  There's no need to include every
     minute detail about your environment, although anything that might
     be different from someone else's environment should be included
     (your path, for instance).

   * Narratives are often useful, given a certain degree of restraint.
     If a person responsible for a bug can see that A was executed, and
     then B and then C, knowing that sequence of events might trigger
     the realization of an intermediate step that was missing, or an
     extra step that might have changed the environment enough to cause
     a visible problem.  Again, restraint is always in order ("I set
     the build running, went to get a cup of coffee (Columbian, cream
     but no sugar), talked to Sheila on the phone, and then THIS
     happened...") but be sure to include anything relevant.

   * Richard Stallman writes, "The fundamental principle of reporting
     bugs usefully is this: *report all the facts*.  If you are not sure
     whether to state a fact or leave it out, state it!"  This holds
     true across all problem reporting systems, for computer software
     or social injustice or motorcycle maintenance.  It is especially
     important in the software field due to the major differences
     seemingly insignificant changes can make (a changed variable, a
     missing semicolon, etc.).

   * Submit only *one* problem with each Problem Report.  If you have
     multiple problems, use multiple PRs.  This aids in tracking each
     problem and also in analyzing the problems associated with a given
     program.

   * It never hurts to do a little research to find out if the bug
     you've found has already been reported.  Most software releases
     contain lists of known bugs in the Release Notes which come with
     the software; see your system administrator if you don't have a
     copy of these.

   * The more closely a PR adheres to the standard format, the less
     interaction is required by a database administrator to route the
     information to the proper place.  Keep in mind that anything that
     requires human interaction also requires time that might be better
     spent in actually fixing the problem.  It is therefore in
     everyone's best interest that the information contained in a PR be
     as correct as possible (in both format and content) at the time of
     submission.


File: gnats.info,  Node: edit-pr,  Next: query-pr,  Prev: send-pr,  Up: Invoking the tools

Editing existing Problem Reports
================================

   Use `edit-pr' to make changes to existing PRs in the database.
`edit-pr' is both a shell script and a Lisp program for GNU Emacs.
Both implementations are essentially identical, though the Emacs
interface provides interactive prompting for some of the fields.

   `edit-pr' first examines the PR you wish to edit and locks it if it
is not already locked.  This is to prevent you from editing a PR at the
same time as another user.  If the PR you wish to edit is already in the
process of being edited, `edit-pr' tells you the name of the person who
owns the lock.

   You may edit any field in the database that you wish.  We recommend
that you avoid deleting any information in the TEXT and MULTITEXT
fields (such as `>Description:' and `>How-To-Repeat:' (*note Problem
Report format: Fields.).  We also recommend that you record the final
solution to the problem in the `>Fix:' field for future reference.

   If you change the `>Responsible:' field, `edit-pr' prompts you to
supply a reason for the change.  `edit-pr' then mails copies of the
change message to the previous responsible party, and to the new
responsible party.  The change is then recorded in the `>Audit-Trail:'
section of the PR as follows:

`Responsible-Changed-<From>-<To>': The value change, supplied
     automatically by `edit-pr'.

`Responsible-Changed-By': Your name here, supplied
     automatically by `edit-pr'.

`Responsible-Changed-When': The current date, supplied
     automatically by `edit-pr'.

`Responsible-Changed-Why': Your reason for the change; you
     are prompted for this.

   If you change the `>State:' field, you are prompted to supply a
reason for the change.  Copies of the change message are then mailed to
the responsible party, and to the original submitter of the Problem
Report.  The change is then recorded in the `Audit-Trail' section of
the PR as follows:

`State-Changed-<From>-<To>': The value change, supplied
     automatically by `edit-pr'.

`State-Changed-By': Your name here, supplied
     automatically by `edit-pr'.

`State-Changed-When': The current date, supplied
     automatically by `edit-pr'.

`State-Changed-Why': Your reason for the change; you are
     prompted for this.

   The PR is then resubmitted to the database, and the index is updated
(*note The `index' file: index file.).  For information on `pr-edit',
the main driver for `edit-pr', see *Note Internal utilities: Internal
utils.

* Menu:

* edit-pr in Emacs::        Using `edit-pr' from within Emacs
* edit-pr from the shell::  Invoking `edit-pr' from the shell